AmigActive 10

home *** CD-ROM | disk | FTP | other *** search

/ AmigActive 10 / AACD 10.iso / AACD / Programming / mpatrol / man / cat3 / mpatrol.3

Wrap

Text File | 2000-05-16 | 63.6 KB | 1,321 lines

MPATROL(3) mpatrol library MPATROL(3) NNAAMMEE mpatrol - dynamic memory allocation and tracing library SSYYNNOOPPSSIISS #include <mpatrol.h> void *malloc(size_t size); void *calloc(size_t nelem, size_t size); void *memalign(size_t align, size_t size); void *valloc(size_t size); void *pvalloc(size_t size); char *strdup(const char *str); char *strndup(const char *str, size_t size); char *strsave(const char *str); char *strnsave(const char *str, size_t size); void *realloc(void *ptr, size_t size); void *recalloc(void *ptr, size_t nelem, size_t size); void *expand(void *ptr, size_t size); void free(void *ptr); void cfree(void *ptr, size_t nelem, size_t size); void *operator new(size_t size); void *operator new[](size_t size); void operator delete(void *ptr); void operator delete[](void *ptr); void (*set_new_handler(void (*func)(void)))(void); void *memset(void *ptr, int byte, size_t size); void bzero(void *ptr, size_t size); void *memccpy(void *dest, const void *src, int byte, size_t size); void *memcpy(void *dest, const void *src, size_t size); void *memmove(void *dest, const void *src, size_t size); void bcopy(const void *src, void *dest, size_t size); int memcmp(const void *ptr1, const void *ptr2, size_t size); int bcmp(const void *ptr1, const void *ptr2, size_t size); void *memchr(const void *ptr, int byte, size_t size); void *memmem(const void *ptr1, size_t size1, const void *ptr2, size_t size2); int __mp_info(const void *ptr, __mp_allocinfo *info); int __mp_printinfo(const void *ptr); void __mp_memorymap(int stats); void __mp_summary(void); void __mp_check(void); void (*__mp_prologue(void (*func)(const void *, size_t))) (const void *, size_t); void (*__mp_epilogue(void (*func)(const void *))) (const void *); void (*__mp_nomemory(void (*func)(void)))(void); DDEESSCCRRIIPPTTIIOONN The _m_p_a_t_r_o_l _l_i_b_r_a_r_y contains implementations of dynamic Release 1.2 16 May 2000 1 MPATROL(3) mpatrol library MPATROL(3) memory allocation functions for C and C++ suitable for tracing and debugging, and is available on UNIX, AmigaOS, Windows and Netware platforms. The library is intended to be used without requiring any changes to existing user source code except the inclusion of the _m_p_a_t_r_o_l_._h header file, although additional functions are supplied for extra tracing and control. Note that the current version of the mpatrol library is contained in the MMPPAATTRROOLL__VVEERRSSIIOONN pre- processor macro. All of the function definitions in _m_p_a_t_r_o_l_._h can be dis- abled by defining the NNDDEEBBUUGG preprocessor macro, which is the same macro used to control the behaviour of the aasssseerrtt function. If NNDDEEBBUUGG is defined then no macro redefinition of functions will take place and all special mpatrol library functions will evaluate to empty statements. It is intended that the NNDDEEBBUUGG preprocessor macro be defined in release builds. All diagnostics are sent to the file _m_p_a_t_r_o_l_._l_o_g in the current directory by default but this can be changed at run-time. Additional configuration options can also be changed at run-time by setting and altering the MMPPAA-- TTRROOLL__OOPPTTIIOONNSS environment variable. See EENNVVIIRROONNMMEENNTT below for more details. Details of memory allocations and free memory are stored internally as a tree structure for speed and also to allow the best fit allocation algorithm to be used. This also enables the library to perform intelligent resizing of memory allocations and can be used to quickly determine if an address has been allocated on the heap. On systems that support memory protection, the library attempts to detect any illegal memory accesses and display as much information as it can obtain about the address in question and where the illegal memory access occurred. Stack traceback information for every memory allocation is available on some supported platforms, which is useful for determining exactly where a memory allocation was per- formed or for adding meaning to tracing. Symbol names are read from the executable file and also possibly from any required shared libraries, and if the UUSSEEDDEEBBUUGG option is used and is available then the debugging section in the executable file will be read to determine additional source-level information. Memory allocation profiling is supported, with statistics about every memory allocation and deallocation that was made during the execution of a program being written to a file at program termination if the PPRROOFF option is used. The information stored in this file can then be used by the mmpprrooff command to display various tables summarising Release 1.2 16 May 2000 2 MPATROL(3) mpatrol library MPATROL(3) the memory allocation behaviour of the program that pro- duced it. FFUUNNCCTTIIOONNSS The following 14 functions are available as replacements for existing C library functions. To use these you must include _m_p_a_t_r_o_l_._h before all other header files, although on UNIX and Windows platforms (and AmigaOS when using ggcccc) they will be used anyway, albeit with slightly less trac- ing information: mmaalllloocc Allocates _s_i_z_e uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to _s_i_z_e bytes in length. If _s_i_z_e is _0 then the memory allocated will be implicitly rounded up to _1 byte. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc. ccaalllloocc Allocates _n_e_l_e_m elements of _s_i_z_e zero-initialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to _n_e_l_e_m _* _s_i_z_e bytes in length. If _n_e_l_e_m _* _s_i_z_e is _0 then the amount of memory allocated will be implicitly rounded up to _1 byte. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc. mmeemmaalliiggnn Allocates _s_i_z_e uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be aligned to _a_l_i_g_n bytes and can be used to store data of up to _s_i_z_e bytes in length. If _a_l_i_g_n is zero then the default system alignment will be used. If _a_l_i_g_n is not a power of two then it will be rounded up to the nearest power of two. If _a_l_i_g_n is greater than the system page size then it will be truncated to that value. If _s_i_z_e is _0 then the memory allocated will be implicitly rounded up to _1 byte. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc, although the latter will not guarantee the preservation of alignment. Release 1.2 16 May 2000 3 MPATROL(3) mpatrol library MPATROL(3) vvaalllloocc Allocates _s_i_z_e uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be aligned to the system page size and can be used to store data of up to _s_i_z_e bytes in length. If _s_i_z_e is _0 then the memory allocated will be implicitly rounded up to _1 byte. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc, although the latter will not guaran- tee the preservation of alignment. ppvvaalllloocc Allocates _s_i_z_e uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be aligned to the system page size and can be used to store data of up to _s_i_z_e bytes in length. If _s_i_z_e is _0 then the memory allocated will be implicitly rounded up to _1 page, otherwise _s_i_z_e will be implicitly rounded up to a multiple of the system page size. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc, although the latter will not guarantee the preservation of alignment. ssttrrdduupp Allocates exactly enough memory from the heap to duplicate _s_t_r (including the terminating nul char- acter) and returns a pointer to the first byte of the allocation after copying _s_t_r to the newly-allo- cated memory. The pointer returned will have no alignment constraints and can be used to store character data up to the length of _s_t_r. If _s_t_r is NNUULLLL then the null pointer will be returned. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc. ssttrrnndduupp Allocates exactly enough memory from the heap to duplicate _s_t_r (including the terminating nul char- acter) and returns a pointer to the first byte of the allocation after copying _s_t_r to the newly-allo- cated memory. The pointer returned will have no alignment constraints and can be used to store character data up to the length of _s_t_r. If _s_t_r is NNUULLLL then the null pointer will be returned. If the length of _s_t_r is greater than _s_i_z_e then only _s_i_z_e characters will be allocated and copied, with one additional byte for the nul character. If Release 1.2 16 May 2000 4 MPATROL(3) mpatrol library MPATROL(3) there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc. This func- tion is available for backwards compatibility with older C libraries and should not be used in new code. ssttrrssaavvee Allocates exactly enough memory from the heap to duplicate _s_t_r (including the terminating nul char- acter) and returns a pointer to the first byte of the allocation after copying _s_t_r to the newly-allo- cated memory. The pointer returned will have no alignment constraints and can be used to store character data up to the length of _s_t_r. If _s_t_r is NNUULLLL then the null pointer will be returned. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc. This func- tion is available for backwards compatibility with older C libraries and should not be used in new code. ssttrrnnssaavvee Allocates exactly enough memory from the heap to duplicate _s_t_r (including the terminating nul char- acter) and returns a pointer to the first byte of the allocation after copying _s_t_r to the newly-allo- cated memory. The pointer returned will have no alignment constraints and can be used to store character data up to the length of _s_t_r. If _s_t_r is NNUULLLL then the null pointer will be returned. If the length of _s_t_r is greater than _s_i_z_e then only _s_i_z_e characters will be allocated and copied, with one additional byte for the nul character. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee or reallocated with rreeaalllloocc. This func- tion is available for backwards compatibility with older C libraries and should not be used in new code. rreeaalllloocc Resizes the memory allocation beginning at _p_t_r to _s_i_z_e bytes and returns a pointer to the first byte of the new allocation after copying _p_t_r to the newly-allocated memory, which will be truncated if _s_i_z_e is smaller than the original allocation. The pointer returned will be suitably aligned for cast- ing to any type and can be used to store data of up to _s_i_z_e bytes in length. If _p_t_r is NNUULLLL then the Release 1.2 16 May 2000 5 MPATROL(3) mpatrol library MPATROL(3) call will be equivalent to mmaalllloocc. If _s_i_z_e is _0 then the existing memory allocation will be freed and the null pointer will be returned. If _s_i_z_e is greater than the original allocation then the extra space will be filled with uninitialised bytes. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee and can be reallocated again with rreeaall-- lloocc. rreeccaalllloocc Resizes the memory allocation beginning at _p_t_r to _n_e_l_e_m elements of _s_i_z_e bytes and returns a pointer to the first byte of the new allocation after copy- ing _p_t_r to the newly-allocated memory, which will be truncated if _n_e_l_e_m * _s_i_z_e is smaller than the original allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to _n_e_l_e_m * _s_i_z_e bytes in length. If _p_t_r is NNUULLLL then the call will be equivalent to ccaalllloocc. If _n_e_l_e_m * _s_i_z_e is _0 then the existing memory allocation will be freed and the null pointer will be returned. If _n_e_l_e_m * _s_i_z_e is greater than the original allocation then the extra space will be filled with zero-initialised bytes. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee and can be reallocated again with rreeaalllloocc. This function is available for backwards compatibility with older C libraries and ccaalllloocc and should not be used in new code. eexxppaanndd Attempts to resize the memory allocation beginning at _p_t_r to _s_i_z_e bytes and either returns _p_t_r if there was enough space to resize it, or NNUULLLL if the block could not be resized for a particular reason. If _p_t_r is NNUULLLL then the call will be equivalent to mmaalllloocc. If _s_i_z_e is 00 then the existing memory allocation will be freed and the NNUULLLL pointer will be returned. If _s_i_z_e is greater than the original allocation then the extra space will be filled with uninitialised bytes and if _s_i_z_e is less than the original allocation then the memory block will be truncated. If there is not enough space in the heap then the NNUULLLL pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM. The allocated memory must be deallocated with ffrreeee and can be reallo- cated again with rreeaalllloocc. This function is avail- able for backwards compatibility with older C libraries and should not be used in new code. ffrreeee Frees the memory allocation beginning at _p_t_r so the Release 1.2 16 May 2000 6 MPATROL(3) mpatrol library MPATROL(3) memory can be reused by another call to allocate memory. If _p_t_r is NNUULLLL then no memory will be freed. All of the previous contents will be destroyed. ccffrreeee Frees the memory allocation beginning at _p_t_r so the memory can be reused by another call to allocate memory. If _p_t_r is NNUULLLL then no memory will be freed. All of the previous contents will be destroyed. The _n_e_l_e_m and _s_i_z_e parameters are ignored in this implementation. This function is available for backwards compatibility with older C libraries and ccaalllloocc and should not be used in new code. The following 5 functions are available as replacements for existing C++ library functions, but the replacements in _m_p_a_t_r_o_l_._h will only be used if the MMPP__NNOOCCPPLLUUSSPPLLUUSS pre- processor macro is not defined. To use these you must include _m_p_a_t_r_o_l_._h before all other header files, although on UNIX and Windows platforms (and AmigaOS when using ggcccc) they will be used anyway, albeit with slightly less trac- ing information: ooppeerraattoorr nneeww Allocates _s_i_z_e uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to _s_i_z_e bytes in length. If _s_i_z_e is _0 then the memory allocated will be implicitly rounded up to _1 byte. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM - no exceptions will be thrown. The allocated memory must be deal- located with ooppeerraattoorr ddeelleettee. ooppeerraattoorr nneeww[[]] Allocates _s_i_z_e uninitialised bytes from the heap and returns a pointer to the first byte of the allocation. The pointer returned will be suitably aligned for casting to any type and can be used to store data of up to _s_i_z_e bytes in length. If _s_i_z_e is _0 then the memory allocated will be implicitly rounded up to _1 byte. If there is not enough space in the heap then the null pointer will be returned and eerrrrnnoo will be set to EENNOOMMEEMM - no exceptions will be thrown. The allocated memory must be deal- located with ooppeerraattoorr ddeelleettee[[]]. ooppeerraattoorr ddeelleettee Frees the memory allocation beginning at _p_t_r so the memory can be reused by another call to allocate memory. If _p_t_r is NNUULLLL then no memory will be Release 1.2 16 May 2000 7 MPATROL(3) mpatrol library MPATROL(3) freed. All of the previous contents will be destroyed. This function must only be used with memory allocated by ooppeerraattoorr nneeww. ooppeerraattoorr ddeelleettee[[]] Frees the memory allocation beginning at _p_t_r so the memory can be reused by another call to allocate memory. If _p_t_r is NNUULLLL then no memory will be freed. All of the previous contents will be destroyed. This function must only be used with memory allocated by ooppeerraattoorr nneeww[[]]. sseett__nneeww__hhaannddlleerr Installs a low-memory handler specifically for use with ooppeerraattoorr nneeww and ooppeerraattoorr nneeww[[]] and returns a pointer to the previously installed handler, or the null pointer if no handler had been previously installed. This will be called repeatedly by both functions when they would normally return NNUULLLL, and this loop will continue until they manage to allo- cate the requested space. The default low-memory handler for the C++ operators will terminate the program and write an out of memory message to the log file. Note that this function is equivalent to ____mmpp__nnoommeemmoorryy and will replace the handler installed by that function. The following 10 functions are available as replacements for existing C library memory operation functions. To use these you must include _m_p_a_t_r_o_l_._h before all other header files, although on UNIX and Windows platforms (and AmigaOS when using ggcccc) they will be used anyway, albeit with slightly less tracing information: mmeemmsseett Writes _s_i_z_e bytes of value _b_y_t_e to the memory loca- tion beginning at _p_t_r and returns _p_t_r. If _s_i_z_e is 00 then no bytes will be written. If the operation would affect an existing memory allocation in the heap but would straddle that allocation's bound- aries then an error message will be generated in the log file and no bytes will be written. bbzzeerroo Writes _s_i_z_e zero bytes to the memory location beginning at _p_t_r. If _s_i_z_e is 00 then no bytes will be written. If the operation would affect an existing memory allocation in the heap but would straddle that allocation's boundaries then an error message will be generated in the log file and no bytes will be written. This function is available for backwards compatibility with older C libraries and should not be used in new code. mmeemmccccppyy Copies _s_i_z_e bytes from _s_r_c to _d_e_s_t and returns Release 1.2 16 May 2000 8 MPATROL(3) mpatrol library MPATROL(3) NNUULLLL, or copies the number of bytes up to and including the first occurrence of _b_y_t_e if _b_y_t_e exists within the specified range and returns a pointer to the first byte after _b_y_t_e. If _s_i_z_e is 00 or _s_r_c is the same as _d_e_s_t then no bytes will be copied. The source and destination ranges should not overlap, otherwise a warning will be written to the log file. If the operation would affect an existing memory allocation in the heap but would straddle that allocation's boundaries then an error message will be generated in the log file and no bytes will be copied. mmeemmccppyy Copies _s_i_z_e bytes from _s_r_c to _d_e_s_t and returns _d_e_s_t. If _s_i_z_e is 00 or _s_r_c is the same as _d_e_s_t then no bytes will be copied. The source and destina- tion ranges should not overlap, otherwise a warning will be written to the log file. If the operation would affect an existing memory allocation in the heap but would straddle that allocation's bound- aries then an error message will be generated in the log file and no bytes will be copied. mmeemmmmoovvee Copies _s_i_z_e bytes from _s_r_c to _d_e_s_t and returns _d_e_s_t. If _s_i_z_e is 00 or _s_r_c is the same as _d_e_s_t then no bytes will be copied. If the operation would affect an existing memory allocation in the heap but would straddle that allocation's boundaries then an error message will be generated in the log file and no bytes will be copied. bbccooppyy Copies _s_i_z_e bytes from _s_r_c to _d_e_s_t. If _s_i_z_e is 00 or _s_r_c is the same as _d_e_s_t then no bytes will be copied. If the operation would affect an existing memory allocation in the heap but would straddle that allocation's boundaries then an error message will be generated in the log file and no bytes will be copied. This function is available for back- wards compatibility with older C libraries and should not be used in new code. mmeemmccmmpp Compares _s_i_z_e bytes from _p_t_r_1 and _p_t_r_2 and returns 00 if all of the bytes are identical, or returns the byte difference of the first differing bytes. If _s_i_z_e is 00 or _p_t_r_1 is the same as _p_t_r_2 then no bytes will be compared. If the operation would read from an existing memory allocation in the heap but would straddle that allocation's boundaries then an error message will be generated in the log file and no bytes will be compared. bbccmmpp Compares _s_i_z_e bytes from _p_t_r_1 and _p_t_r_2 and returns 00 if all of the bytes are identical, or returns the Release 1.2 16 May 2000 9 MPATROL(3) mpatrol library MPATROL(3) byte difference of the first differing bytes. If _s_i_z_e is 00 or _p_t_r_1 is the same as _p_t_r_2 then no bytes will be compared. If the operation would read from an existing memory allocation in the heap but would straddle that allocation's boundaries then an error message will be generated in the log file and no bytes will be compared. This function is available for backwards compatibility with older C libraries and should not be used in new code. mmeemmcchhrr Searches up to _s_i_z_e bytes in _p_t_r for the first occurrence of _b_y_t_e and returns a pointer to it or NNUULLLL if no such byte occurs. If _s_i_z_e is 00 then no bytes will be searched. If the operation would affect an existing memory allocation in the heap but would straddle that allocation's boundaries then an error message will be generated in the log file and no bytes will be searched. mmeemmmmeemm Searches up to _s_i_z_e_1 bytes in _p_t_r_1 for the first occurrence of _p_t_r_2 (which is exactly _s_i_z_e_2 bytes in length) and returns a pointer to it or NNUULLLL if no such sequence of bytes occur. If _s_i_z_e_1 or _s_i_z_e_2 is 00 then no bytes will be searched. If the operation would affect an existing memory allocation in the heap but would straddle that allocation's bound- aries then an error message will be generated in the log file and no bytes will be searched. The following 8 functions are available as support rou- tines for additional control and tracing in the mpatrol library. To use these you should include the _m_p_a_t_r_o_l_._h header file: ____mmpp__iinnffoo Obtains information about a specific memory alloca- tion by placing statistics about _p_t_r in _i_n_f_o. If _p_t_r does not belong to a previously allocated mem- ory allocation then _0 will be returned, otherwise _1 will be returned and _i_n_f_o will contain the follow- ing information: FFiieelldd DDeessccrriippttiioonn bblloocckk Pointer to first byte of alloc. ssiizzee Size of alloc in bytes. ttyyppee Type of function which allocated memory. aalllloocc Allocation index. rreeaalllloocc Number of times reallocated. tthhrreeaadd Thread identifier. ffuunncc Function in which alloc took place. ffiillee File in which alloc took place. lliinnee Line number at which alloc took place. ssttaacckk Pointer to function call stack. Release 1.2 16 May 2000 10 MPATROL(3) mpatrol library MPATROL(3) ffrreeeedd Indicates if alloc has been freed. ____mmpp__pprriinnttiinnffoo Displays information about a specific memory allo- cation containing _p_t_r to the standard error file stream. If _p_t_r does not belong to a previously allocated memory allocation then _0 will be returned, otherwise _1 will be returned. This func- tion is intended to be called from within a debug- ger. ____mmpp__mmeemmoorryymmaapp If _s_t_a_t_s is non-zero then the current statistics of the mpatrol library will be displayed. If the heap contains at least one allocated, freed or free block then a map of the current heap will also be displayed. ____mmpp__ssuummmmaarryy Displays information about the current state of the mpatrol library, including its settings and any relevant statistics. ____mmpp__cchheecckk Forces the library to perform an immediate check of the overflow buffers of every memory allocation and to ensure that nothing has overwritten any free blocks. ____mmpp__pprroolloogguuee Installs a prologue function to be called before any memory allocation, reallocation or deallocation function. This function will return a pointer to the previously installed prologue function, or the null pointer if no prologue function had been pre- viously installed. The following arguments will be used to call the prologue function: AArrgguummeenntt 11 AArrgguummeenntt 22 CCaalllleedd bbyy _-_1 _s_i_z_e mmaalllloocc, etc. _p_t_r _s_i_z_e rreeaalllloocc, etc. _p_t_r _-_1 ffrreeee, etc. _p_t_r _-_2 ssttrrdduupp, etc. ____mmpp__eeppiilloogguuee Installs an epilogue function to be called after any memory allocation, reallocation or deallocation function. This function will return a pointer to the previously installed epilogue function, or the null pointer if no epilogue function had been pre- viously installed. The following arguments will be used to call the epilogue function: Release 1.2 16 May 2000 11 MPATROL(3) mpatrol library MPATROL(3) AArrgguummeenntt CCaalllleedd bbyy _p_t_r mmaalllloocc, rreeaalllloocc, ssttrrdduupp, etc. _-_1 ffrreeee, etc. ____mmpp__nnoommeemmoorryy Installs a low-memory handler and returns a pointer to the previously installed handler, or the null pointer if no handler had been previously installed. This will be called once by C memory allocation functions, and repeatedly by C++ memory allocation functions, when they would normally return NNUULLLL. Note that this function is equivalent to sseett__nneeww__hhaannddlleerr and will replace the handler installed by that function. LLIINNKKIINNGG In order to use the mpatrol library on UNIX platforms, the following libraries must be linked in before any other library that defines dynamic memory allocation functions with the same names: LLiibbrraarryy RReeaassoonn _-_l_m_p_a_t_r_o_l To use this library. _-_l_e_l_f If built with FFOORRMMAATT==FFOORRMMAATT__EELLFF3322. _-_l_b_f_d _-_l_i_b_e_r_t_y If built with FFOORRMMAATT==FFOORRMMAATT__BBFFDD. _-_l_p_t_h_r_e_a_d If built with MMPP__TTHHRREEAADDSS__SSUUPPPPOORRTT. On UNIX platforms, if there were no calls to memory allo- cation functions before _-_l_m_p_a_t_r_o_l appears on the link line then the mpatrol library will not be linked in. However, this can be overridden by placing _-_u_m_a_l_l_o_c just before that point. You may also wish to set your core file size limit to be zero before running any programs linked with the mpatrol library as the extra memory that the library uses can make such files much larger than normal, and if you are plan- ning on using a symbolic debugger then you won't need the core files anyway. EENNVVIIRROONNMMEENNTT The library can read certain options at run-time from an environment variable called MMPPAATTRROOLL__OOPPTTIIOONNSS. This vari- able must contain one or more valid option keywords from the list below and must be no longer than 1024 characters in length. If MMPPAATTRROOLL__OOPPTTIIOONNSS is unset or empty then the default settings will be used. The syntax for options specified within the MMPPAA-- TTRROOLL__OOPPTTIIOONNSS environment variable is OOPPTTIIOONN or OOPPTTIIOONN=_V_A_L_U_E, where OOPPTTIIOONN is a keyword from the list below and _V_A_L_U_E is the setting for that option. If _V_A_L_U_E Release 1.2 16 May 2000 12 MPATROL(3) mpatrol library MPATROL(3) is numeric then it may be specified using binary, octal, decimal or hexadecimal notation, with binary notation beginning with either _0_b or _0_B. If _V_A_L_U_E is a character string containing spaces then it may be quoted using dou- ble quotes. No whitespace may appear between the _= sign, but whitespace must appear between different options. Note that option keywords can be given in lowercase as well as uppercase, or a mixture of both. AALLLLOOCCBBYYTTEE=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies an 8-bit byte pattern with which to pre- fill newly-allocated memory. This can be used to detect the use of memory which has not been ini- tialised after allocation. Note that this setting will not affect memory allocated with ccaalllloocc or rreeccaalllloocc as these functions always prefill allo- cated memory with an 8-bit byte pattern of zero. Default value: AALLLLOOCCBBYYTTEE=_0_x_F_F. AALLLLOOCCSSTTOOPP=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies an allocation index at which to stop the program when it is being allocated. When the num- ber of memory allocations reaches this number the program will be halted, and its state may be exam- ined at that point by using a suitable debugger. Note that this setting will be ignored if its value is zero. Default value: AALLLLOOCCSSTTOOPP=_0. AALLLLOOWWOOFFLLOOWW Specifies that a warning rather than an error should be produced if any memory operation function overflows the boundaries of a memory allocation, and that the operation should still be performed. This option is provided for circumstances where it is desirable for the memory operation to be per- formed, regardless of whether it is erroneous or not. AAUUTTOOSSAAVVEE=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the frequency at which to periodically write the profiling data to the profiling output file. When the total number of profiled memory allocations and deallocations is a multiple of this number then the current profiling information will be written to the profiling output file. This option can be used to instruct the mpatrol library to dump out any profiling information just before a fatal error occurs in a program, for example. Note that this setting will be ignored if its value is zero. Default value: AAUUTTOOSSAAVVEE=_0. CCHHEECCKK=_u_n_s_i_g_n_e_d _r_a_n_g_e Specifies a range of allocation indices at which to check the integrity of free memory and overflow Release 1.2 16 May 2000 13 MPATROL(3) mpatrol library MPATROL(3) buffers. The range must be specified as no more than two unsigned integers separated by a dash. If numbers on either the left side or the right side of the dash are omitted then they will be assumed to be _0 and _i_n_f_i_n_i_t_y respectively. A value of _0 on its own indicates that no such checking will ever be performed. This option can be used to speed up the execution speed of the library at the expense of checking. Default value: CCHHEECCKK=_-. CCHHEECCKKAALLLL Equivalent to the CCHHEECCKKAALLLLOOCCSS, CCHHEECCKKRREEAALLLLOOCCSS and CCHHEECCKKFFRREEEESS options specified together. CCHHEECCKKAALLLLOOCCSS Checks that no attempt is made to allocate a block of memory of size zero. A warning will be issued for every such case. CCHHEECCKKFFRREEEESS Checks that no attempt is made to deallocate a NNUULLLL pointer. A warning will be issued for every such case. CCHHEECCKKRREEAALLLLOOCCSS Checks that no attempt is made to reallocate a NNUULLLL pointer or resize an existing block of memory to size zero. Warnings will be issued for every such case. DDEEFFAALLIIGGNN=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the default alignment for general-purpose memory allocations, which must be a power of two (and will be rounded up to the nearest power of two if it is not). The default alignment for a partic- ular system is calculated at run-time. FFAAIILLFFRREEQQ=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the frequency at which all memory alloca- tions will randomly fail. For example, a value of _1_0 will mean that roughly 1 in 10 memory alloca- tions will fail, but a value of _0 will disable all random failures. This option can be useful for stress-testing an application. Default value: FFAAIILLFFRREEQQ=_0. FFAAIILLSSEEEEDD=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the random number seed which will be used when determining which memory allocations will ran- domly fail. A value of _0 will instruct the library to pick a random seed every time it is run. Any other value will mean that the random failures will be the same every time the program is run, but only as long as the seed stays the same. Default value: Release 1.2 16 May 2000 14 MPATROL(3) mpatrol library MPATROL(3) FFAAIILLSSEEEEDD=_0. FFRREEEEBBYYTTEE=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies an 8-bit byte pattern with which to pre- fill newly-freed memory. This can be used to detect the use of memory which has just been freed. It is also used internally to ensure that freed memory has not been overwritten. Note that the freed memory may be reused the next time a block of memory is allocated and so once memory has been freed its contents are not guaranteed to remain the same as the specified byte pattern. Default value: FFRREEEEBBYYTTEE=_0_x_5_5. FFRREEEESSTTOOPP=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies an allocation index at which to stop the program when it is being freed. When the memory allocation with the specified allocation index is to be freed the program will be halted, and its state may be examined at that point using a suit- able debugger. Note that this setting will be ignored if its value is zero. Default value: FFRREEEESSTTOOPP=_0. HHEELLPP Displays a quick-reference option summary to the ssttddeerrrr file stream. LLAARRGGEEBBOOUUNNDD=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the limit in bytes up to which memory allocations should be classified as large alloca- tions for profiling purposes. This limit must be greater than the small and medium bounds. Default value: LLAARRGGEEBBOOUUNNDD=_2_0_4_8. LLIIMMIITT=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the limit in bytes at which all memory allocations should fail if the total allocated mem- ory should increase beyond this. This can be used to stress-test software to see how it behaves in low memory conditions. The internal memory used by the library itself will not be counted as part of the total heap size, but on some systems there may be a small amount of memory required to initialise the library itself. Note that this setting will be ignored if its value is zero. Default value: LLIIMMIITT=_0. LLOOGGAALLLL Equivalent to the LLOOGGAALLLLOOCCSS, LLOOGGRREEAALLLLOOCCSS, LLOOGGFFRREEEESS and LLOOGGMMEEMMOORRYY options specified together. LLOOGGAALLLLOOCCSS Specifies that all memory allocations are to be logged and sent to the log file. Note that any memory allocations made internally by the library Release 1.2 16 May 2000 15 MPATROL(3) mpatrol library MPATROL(3) will not be logged. LLOOGGFFIILLEE=_s_t_r_i_n_g Specifies an alternative file in which to place all diagnostics from the mpatrol library. A filename of _s_t_d_e_r_r will send all diagnostics to the ssttddeerrrr file stream and a filename of _s_t_d_o_u_t will do the equivalent with the ssttddoouutt file stream. Note that if a problem occurs while opening the log file or if any diagnostics require to be displayed before the log file has had a chance to be opened then they will be sent to the ssttddeerrrr file stream. Default value: LLOOGGFFIILLEE=_m_p_a_t_r_o_l_._l_o_g LLOOGGFFRREEEESS Specifies that all memory deallocations are to be logged and sent to the log file. Note that any memory deallocations made internally by the library will not be logged. LLOOGGMMEEMMOORRYY Specifies that all memory operations are to be logged and sent to the log file. These operations will be made by calls to functions such as mmeemmsseett and mmeemmccppyy. Note that any memory operations made internally by the library will not be logged. LLOOGGRREEAALLLLOOCCSS Specifies that all memory reallocations are to be logged and sent to the log file. Note that any memory reallocations made internally by the library will not be logged. MMEEDDIIUUMMBBOOUUNNDD=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the limit in bytes up to which memory allocations should be classified as medium alloca- tions for profiling purposes. This limit must be greater than the small bound but less than the large bound. Default value: MMEEDDIIUUMMBBOOUUNNDD=_2_5_6. NNOOFFRREEEE Specifies that the mpatrol library should keep all reallocated and freed memory allocations. Such freed memory allocations will then be flagged as freed and can be used by the library to provide better diagnostics. However, as no system memory will ever be reused by the mpatrol library, this option can quickly lead to a shortage of available system memory for a process. Note that this option will always force a memory reallocation to return a pointer to newly-allocated memory, but the eexxppaanndd function will never be affected by this option. NNOOPPRROOTTEECCTT Specifies that the mpatrol library's internal data Release 1.2 16 May 2000 16 MPATROL(3) mpatrol library MPATROL(3) structures should not be made read-only after every memory allocation reallocation or deallocation. This may significantly speed up execution but this will be at the expense of less safety if the pro- gram accidentally overwrites some of the library's internal data structures. Note that this option has no effect on systems that do not support memory protection. OOFFLLOOWWBBYYTTEE=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies an 8-bit byte pattern with which to fill the overflow buffers of all memory allocations. This is used internally to ensure that nothing has been written beyond the beginning or the end of a block of allocated memory. Note that this setting will only have an effect if the OOFFLLOOWWSSIIZZEE option is in use. Default value: OOFFLLOOWWBBYYTTEE=_0_x_A_A. OOFFLLOOWWSSIIZZEE=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the size in bytes to use for all overflow buffers, which must be a power of two (and will be rounded up to the nearest power of two if it is not). This is used internally to ensure that noth- ing has been written beyond the beginning or the end of a block of allocated memory. Note that this setting specifies the size for only one of the overflow buffers given to each memory allocation; the other overflow buffer will have an identical size. No overflow buffers will be used if this setting is zero. Default value: OOFFLLOOWWSSIIZZEE=_0. OOFFLLOOWWWWAATTCCHH Specifies that watch point areas should be used for overflow buffers rather than filling with the over- flow byte. This can significantly reduce the speed of program execution. Note that this option has no effect on systems that do not support watch point areas. PPAAGGEEAALLLLOOCC=_L_O_W_E_R|_U_P_P_E_R Specifies that each individual memory allocation should occupy at least one page of virtual memory and should be placed at the lowest or highest point within these pages. This allows the library to place an overflow buffer of one page on either side of every memory allocation and write-protect these pages as well as all free and freed memory. Note that this option has no effect on systems that do not support memory protection, and is disabled by default on other systems as it can slow down the speed of program execution. PPRREESSEERRVVEE Specifies that any reallocated or freed memory Release 1.2 16 May 2000 17 MPATROL(3) mpatrol library MPATROL(3) allocations should preserve their original con- tents. This option must be used with the NNOOFFRREEEE option and has no effect otherwise. PPRROOFF Specifies that all memory allocations and dealloca- tions are to be profiled and sent to the profiling output file. Memory reallocations are treated as a memory deallocation immediately followed by a mem- ory allocation. PPRROOFFFFIILLEE=_s_t_r_i_n_g Specifies an alternative file in which to place all memory allocation profiling information from the mpatrol library. A filename of _s_t_d_e_r_r will send this information to the ssttddeerrrr file stream and a filename of _s_t_d_o_u_t will do the equivalent with the ssttddoouutt file stream. Note that if a problem occurs while opening the profiling output file then the profiling information will be sent to the ssttddeerrrr file stream. Default value: PPRROOFFFFIILLEE=_m_p_a_t_r_o_l_._o_u_t. PPRROOGGFFIILLEE=_s_t_r_i_n_g Specifies an alternative filename with which to locate the executable file containing the program's symbols. On most systems, the library will auto- matically be able to determine this filename, but on a few systems this option may have to be used before any or all symbols can be read. RREEAALLLLOOCCSSTTOOPP=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies a reallocation index at which to stop the program when a memory allocation is being reallo- cated. If the AALLLLOOCCSSTTOOPP option is non-zero then the program will be halted when the allocation matching that allocation index is reallocated the specified number of times. Otherwise the program will be halted the first time any allocation is reallocated the specified number of times. Note that this setting will be ignored if its value is zero. Default value: RREEAALLLLOOCCSSTTOOPP=_0. SSAAFFEESSIIGGNNAALLSS Instructs the library to save and replace certain signal handlers during the execution of library code and to restore them afterwards. This was the default behaviour in version 1.0 of the mpatrol library and was changed since some memory-intensive programs became very hard to interrupt using the keyboard, thus giving the impression that the pro- gram or system had hung. SSHHOOWWAALLLL Equivalent to the SSHHOOWWFFRREEEEDD, SSHHOOWWUUNNFFRREEEEDD, SSHHOOWWMMAAPP and SSHHOOWWSSYYMMBBOOLLSS options specified together. Release 1.2 16 May 2000 18 MPATROL(3) mpatrol library MPATROL(3) SSHHOOWWFFRREEEEDD Specifies that a summary of all of the freed memory allocations should be displayed at the end of pro- gram execution. This option must be used in con- junction with the NNOOFFRREEEE option and this step will not be performed if an abnormal termination occurs or if there were no freed allocations. SSHHOOWWMMAAPP Specifies that a memory map of the entire heap should be displayed at the end of program execu- tion. This step will not be performed if an abnor- mal termination occurs or if the heap is empty. SSHHOOWWSSYYMMBBOOLLSS Specifies that a summary of all of the function symbols read from the program's executable file should be displayed at the end of program execu- tion. This step will not be performed if an abnor- mal termination occurs or if no symbols could be read from the executable file. SSHHOOWWUUNNFFRREEEEDD Specifies that a summary of all of the unfreed mem- ory allocations should be displayed at the end of program execution. This step will not be performed if an abnormal termination occurs or if there are no unfreed allocations. SSMMAALLLLBBOOUUNNDD=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the limit in bytes up to which memory allocations should be classified as small alloca- tions for profiling purposes. This limit must be greater than zero but less than the medium and large bounds. Default value: SSMMAALLLLBBOOUUNNDD=_3_2. UUNNFFRREEEEDDAABBOORRTT=_u_n_s_i_g_n_e_d _i_n_t_e_g_e_r Specifies the minimum number of unfreed allocations at which to abort the program just before program termination. A summary of all the allocations will be displayed on the standard error file stream before aborting. This option may be handy for use in batch tests as it can force tests to fail if they do not free up a minimum number of memory allocations. Note that this setting will be ignored if its value is zero. Default value: UUNNFFRREEEEDDAABBOORRTT=_0. UUSSEEDDEEBBUUGG Specifies that any debugging information in the executable file should be used to obtain additional source-level information. This option will only have an effect if the executable file contains a compiler-generated line number table and will be Release 1.2 16 May 2000 19 MPATROL(3) mpatrol library MPATROL(3) ignored if the mpatrol library was built to support an object file access library that cannot read line tables from object files. UUSSEEMMMMAAPP Specifies that the library should use mmmmaapp instead of ssbbrrkk to allocate system memory on UNIX plat- forms. This option should be used if there are problems when using the mpatrol library in combina- tion with another malloc library which uses ssbbrrkk to allocate its memory. It is ignored on systems that do not support the mmmmaapp system call. SSEEEE AALLSSOO mmppaattrrooll(1), mmpprrooff(1), mmlleeaakk(1), mmmmaapp(2), ssbbrrkk(2), mmaall-- lloocc(3), mmeemmoorryy(3), ssttrriinngg(3), aasssseerrtt(3), eellff(3e), bbffdd(3). The mpatrol manual, reference card and FAQ. http://www.cbmamiga.demon.co.uk/mpatrol/ AAUUTTHHOORR Graeme S. Roy <graeme@epc.co.uk> CCOOPPYYRRIIGGHHTT Copyright (C) 1997-2000 Graeme S. Roy <graeme@epc.co.uk> This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library Gen- eral Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. Release 1.2 16 May 2000 20